gibbonsecr manual v0.0
3 April 2016
1 Overview
The gibbonsecr software package uses Spatially Explicit Capture–Recapture (SECR) methods to estimate the density of gibbon groups from acoustic survey data. This manual begins with a brief introduction to the theory behind SECR and then describes the main components of the user interface.
2 Introduction to SECR
Over the past decade SECR has become an increasingly popular tool for wildlife population assessment and has been used to analyse survey data for a wide range of animal groups. The main advantage of this method over traditional capture-recapture techniques is that it allows direct estimation of population density rather than abundance. Traditional capture-recapture methods can only provide density estimates through the use of separate estimates or assumptions about the size of the sampled area. In SECR however, density is estimated directly from the survey data by using information contained in the pattern of the recaptures to make inferences about the spatial location of animals. By extracting spatial information in this way, SECR provides estimates of density without requiring the exact locations of the detected animals to be known in advance.
2.1 Basic setup
The basic data collection setup for an SECR analysis consists of a spatial array of detectors. Detectors come in a variety of different forms, including traps which physically detain the animals, and proximity detectors which do not. The use of proximity detectors makes it possible for an animal to be detected at more than one detector (i.e. recaptured) during a single sampling occasion.
The plot below shows a hypothetical array of proximity detectors, with red squares representing detections of the same animal (or the same group in the case of gibbon surveys) and black squares representing no detections.
The pattern of the detections (i.e. the pattern of the recapture data) contains information about the true location of the animal/group; an intuitive guess would be that the true location is somewhere near the cluster of red detectors. The plot below shows a set of probability contours for this unknown location, given the recapture data.
In the case of acoustic gibbon surveys the listening posts can be treated as proximity detectors and the same logic can be applied to obtain information on the locations of the detected groups. However, the design shown in the figure above would obviously be impractical for gibbon surveys. The next figure shows probability contours for a more realistic array of listening posts where a group has been detected at two of the posts.
The obvious conclusion here is that using smaller arrays of detectors results in less information about the unknown locations.
2.2 Estimated bearings
SECR also allows supplementary information on group location to be included in the analysis in addition to the recapture data, for example in the form of estimated bearings to the detected animals/groups. The next figure illustrates how taking account of information contained in the estimated bearings can provide better quality information on unknown locations.
Using estimated bearings in this way can lead to density estimates that are less biased and more precise than using recapture data alone. Since the precision of bearing estimates is usually unknown, SECR methods need to estimate it from the data. This requires the choice of a bearing error distribution. The figure below shows two common choices of distribution for modelling bearing errors – the von Mises and the wrapped Cauchy. The colour of the lines in these plots indicate the value of the precision parameter (and which need to be estimated from the survey data).
2.3 Estimated distances
TODO
2.4 Detection functions
Another key feature of SECR is that the probability of detecting a (calling) gibbon group at a given location is modelled as a function of distance between the group and the listening post. This function – referred to as the detection function – is typically assumed to belong to one of two main types of function: the half normal or the hazard rate. The specific shape of the detection function depends on the value of its parameters, which need to be estimated from the survey data. The half normal has two parameters: g0 and sigma: the g0 parameter gives the detection probability at zero distance and the sigma parameter controls the width of the function. The hazard rate has three parameters: g0, sigma and z. The g0 and sigma parameters have the same interpretation as for the half normal, while the z parameter controls the shape of the ‘shoulder’ and adds a greater degree of flexibility. The figure below illustrates the shape of these detection functions for a range of parameter values.
2.5 Detection surface
Associating a detection function with each listening post allows us to calculate the overall probability of detection – i.e. the probability of detection at at least one listening post – for any given location. The figure below illustrates this concept using a heat map of a detection surface where color indicates overall detection probability.
The region near the centre of this surface is close to the listening post array and has the highest detection probability. In this case, an group located close to the detectors will almost certainly be detected. The detection probability decreases as distance from the detectors increases.
2.6 Effective sampling area
The shape of the detection surface is related to the size of the effective sampling area. Since the region close to the detectors has a very high detection probability, most animals/groups within this region will be detected and it will therefore be sampled almost perfectly. However, regions where the detection probability is less than 1 will not be completely sampled as some animal/groups in these areas will be missed. The figure below illustrates this idea for a series of arbitrary detection surfaces.
The first plot in this figure shows a flat surface where the detection probability is 0.5 everywhere. In this scenario every animal/group has a 50% chance of being detected. If the area covered by the surface was 10km2, then the effective sampling area would be 10km2 x 0.5 = 5km2. Using this detection process we would expect to detect the same number of groups as we would if we had perfectly sampled an area of 5km2. In the second plot, half of the area is sampled perfectly and the other half is not sampled at all, so this has the same effective sampling area as the first plot. The third plot has a detection gradient and isn’t as intuitive to interpret. However, the general to calculate the effective survey area is to calculate the volume under the detection surface. The third plot has the same volume as the other two, so it has the same effective area.
3 Loading the software
TODO
3.1 Launch from R
3.1.1 Install R
Make sure you have the latest version of R installed.
Optionally you can also install RStudio which is a more user-friendly interface to R and (e.g. it supports syntax highlighting and auto-completion).
3.1.2 Install prerequisites
TODO
3.1.3 Install gibbonsecr
TODO
3.1.4 Launch the interface
Once everything is installed you can launch the user interface by opening R (or RStudio) and typing the following lines into the console.
library(gibbonsecr)
gui()3.2 Launch from a desktop icon
TODO
3.2.1 Download the files
TODO
3.2.2 Make a shortcut icon
TODO
4 Data import
The first step in conducting an analysis is to import your survey data. This is done via the Data tab, which is shown in the screenshot below.
**SCREENSHOT**
4.1 CSV files
As a minimum requirement you need to prepare a detections file and a posts file, both of which must be in .csv format. You can also include an optional covariates file (which also needs to be in .csv format). Advice on how to structure these files is given in the sections below. The file paths to your data files can be entered manually into the text entry boxes in the CSV files section, or you can navigate to the file path using the ... button.
4.1.1 Detections
The detections file needs to contain a record of each detection, with one row per detection. For example, if group 1 was recorded at listening posts A and B then this would count as two detections. This file needs to have the following columns:
- array – Id for the array
- occasion – Id for day of the survey (typically an integer from 1 to 4)
- post – Id for the listening post
- group – Id for the detected group
- bearing – Estimated bearing to the detected group
- distance – Estimated distance to the deteted group (optional)
The table below shows example entries for detections made at one array during a one-day (i.e. single-occasion) survey.
| array | occasion | post | group | bearing |
|---|---|---|---|---|
| 6 | 1 | A | 6_A | 170 |
| 6 | 1 | B | 6_B | 192 |
| 6 | 1 | B | 6_A | 180 |
| 6 | 1 | B | 6_C | 40 |
| 6 | 1 | C | 6_B | 220 |
| 6 | 1 | C | 6_C | 36 |
4.1.2 Posts
The posts file contains information on the location and usage of the listening posts. This file needs to have one row per listening post and should contain the following columns:
- array – Id for the array
- post – Id for the listening post
- x – Longitude coordinate (in metric units)
- y – Latitude coordinate (in metric units)
- usage – Indicator showing the sampling days on which the posts were manned E.g. if on a 3-day survey a particular post was manned on day 1 and day 3 but for some reason not on day 2, then
101would be entered in the usage column for that post. The number of digits in the usage column should be equal to the number of sampling days for the array.
The table below shows example entries for posts at one array during a one-day survey.
| array | post | x | y | usage |
|---|---|---|---|---|
| 6 | A | 690085 | 1557174 | 1 |
| 6 | B | 690570 | 1557163 | 1 |
| 6 | C | 691082 | 1557128 | 1 |
4.1.3 Covariates
The covariates file should contains values for any other variables associated with the survey data. This file needs to have one row per samping day for each listening post and should contain at least the following columns:
- array – Id for the array
- post – Id for the listening post
- occasion – Id for day of the survey (typically an integer from 1 to 4)
These columns can all be used as covariates themselves, but any additional covariates should be added using additional columns. Use underscores _ instead of full stops for the covariate names.
The table below shows example covariates at a single array for a one-day survey.
| array | post | occasion | month | observer |
|---|---|---|---|---|
| 6 | A | 1 | June | Rod |
| 6 | B | 1 | June | Jane |
| 6 | C | 1 | June | Freddy |
4.1.3.1 Covariate levels
TODO
4.2 Data details
Once the paths to the .csv files have been entered, select the appropriate units from the Data details dropdown boxes for your estimated bearings data (and estimated distances data if it was collected). Note that the current version of the software only allows Type to be set to continuous since interval methods for bearings and distances have not yet been implemented.
5 Making a mask
The SECR model fitting procedure requires the use of a mask, which is a fine grid of latitude and longitude coordinates around each array of listening posts. When an SECR model is fitted, the mask is used to provide a set of plausible candidate locations for each detected group. It is important to select a suitable mask to avoid unreliable results.
**SCREENSHOT**
5.1 Mask size and resolution
There are two main settings you need to consider when defining a mask – the buffer and the spacing – which you can specify in the Mask tab.
5.1.1 Buffer
The buffer defines the maximum distance between each mask point and the closest listening post. It needs to be large enough so that the region it encompasses contains all plausible locations for the detected groups, but it shouldn’t be unnecessarily large. Buffer distances that are too small will lead to underestimates of the effective sampling area and overestimates of density. However, increasing the buffer distance also increases the number of mask points, which means that the models will take longer to run, so the buffer also shouldn’t be larger than it needs to be. The ideal buffer distance is the distance at which the overall detection probability drops to zero.
A good way to check whether the buffer distance is large enough is to look at the detection surface, which you can plot after fitting a model (see the section on plotting results). The detection surface plot produced by gibbonsecr is the same size as the mask, so the colour at the edge of the plot will show you the overall detection probability at the buffer distance. If the detection probability is greater than zero at the buffer distance then you should increase the buffer distance, re-fit the model and re-check the detection surface plot.
To illustrate this issue, the figure below shows a series of detection surfaces from models that were fitted using mask buffers of 1000m, 10000m and 5000m respectively.
The buffer in the first plot is too small as the detection probability at the edge of the mask is much greater than zero. In this case it is therefore extremely likely that the true locations of some of the detected groups will be outside the buffer zone. The buffer in the second plot is ten times greater than the buffer in the first and the detection probability at the edge of the mask is zero. We would expect the density estimate to be unbiased and in the density estimate is around 75% lower than the estimate in plot 1 (which suggests that the estimate in plot 1 is a severe overestimate). The buffer in the third plot is intermediate between the other two. The detection probability is still zero at the buffer distance, but the estimated density is very similar to plot 2, so it doesn’t look to be biased. The computation time was also much quicker than for plot 2. In this case the mask in the third plot would be preferred.
5.1.2 Spacing
The buffer spacing is the distance between adjacent mask points. Decreasing the spacing will increase the resolution and increase the total number of mask points. Smaller spacings therefore provide a greater number of candidate locations and lead to more reliable results. However, increasing the number of mask points has a cost in terms of computing time and if the spacing is too small then models may take a very long time to run. As a general rule of thumb, try to use the smallest spacing that is practical given the speed of your computer, but try not to use spacings larger than 250m.
5.2 Shapefiles
TODO
5.2.1 Region
TODO
5.2.2 Habitat
TODO
6 Model fitting
Once you have made a mask you can move on the Model tab and start fitting some SECR models.
**SCREENSHOT**
Specifying a model is split into two steps: (i) choosing what kind of detection function and bearing error distribution you want to use, and (ii) deciding whether to fix any parameter values or model them using the available covariates. These steps are described in more detail below.
6.1 Model options
TODO
6.2 Model parameters
TODO
6.2.1 Formulas
TODO
6.2.2 Fixing parameter values
TODO
6.2.3 Estimating g0
TODO
6.2.4 Estimating calling probability
TODO
7 Plotting results
TODO
8 Model selection
TODO
8.1 AIC
TODO
8.2 Model plausibility
TODO
10 Reporting bugs
TODO